home *** CD-ROM | disk | FTP | other *** search
/ Ultra Pack / UltraComputing Technology Demos and Tools.iso / proctool / proc.help.txt < prev    next >
Text File  |  1996-04-03  |  14KB  |  434 lines
  1. proctool_info
  2. ProCtool
  3.  
  4.  
  5. ProCtool is a tool for monitoring and controlling processes on a system.
  6. It is available on Solaris only.
  7.  
  8.  
  9. Proctool is available in binary form for free.  It may also be freely
  10. distributed within and outside of Sun Microsystems. It is not an official
  11. Sun Microsystems product, and it carries no implied support or endorsement
  12. from Sun Microsystems.  Please do not attempt to log proctool support
  13. calls with the Sun Answer Center.
  14.  
  15.  
  16. The authors, however, intend to support this product on their own time and
  17. we encourage you to file bug reports, requests for enhancements and/or
  18. comments with us at:
  19.  
  20.  
  21.     morgan.herrington@west.sun.com   (Morgan Herrington)
  22.  
  23.  
  24. and
  25.  
  26.  
  27.     walter.nielsen@eng.sun.com      (Walter Nielsen)
  28.  
  29.  
  30. We will announce new versions of proctool outside of Sun on the newsgroup
  31. "comp.unix.solaris", however, we will also maintain a separate "notification"
  32. alias which we will use to inform interested users about new releases of
  33. the tool.  If you would like to be added, just send a short email giving
  34. us permission to add you (along with your preferred email address).
  35.  
  36.  
  37. We intend to keep the latest version(s) of proctool (with documentation,
  38. help and startup files) available to the general internet, via anonymous
  39. ftp from:
  40.  
  41.  
  42.     sunsite.unc.edu:/pub/sun-info/mde/proctool/proctool_X.Y.tar.Z
  43.  
  44.  
  45. and available within Sun at:
  46.  
  47.  
  48.     newstop.ebay:/sun/MDE/Performance/proctool/proctool_X.Y.tar.Z
  49.  
  50.  
  51. (where X.Y is replaced by the appropriate Solaris version number).  Proctool
  52. sometimes appears on other servers, however, these other locations are not
  53. maintained by the authors.  If you would like to verify that the binaries
  54. you download have not been tampered with, please contact the authors and
  55. ask for checksums using "sum" or "md5" (whichever you prefer).
  56.  
  57.  
  58. We have chosen not to release source for proctool.  We feel this reduces our
  59. support burden and simplifies our relationship with Sun.  Please contact us
  60. directly for any special situations.
  61.  
  62. FAQ:
  63.  
  64. ---
  65.  
  66.  
  67. Q: I applied some patches to my Solaris kernel, now ProCtool won't run.
  68.  
  69.  
  70. A: ProCtool uses the uname() call to check with OS version is running on.  
  71. Some patches change the value uname() returns.  To override this, use the
  72. -v option to ProCtool.   Note that ProCtool version 2.X runs only on Solaris
  73. version 2.X.
  74.  
  75.  
  76. Q: What does the following error message mean?
  77.  
  78.  
  79.     Insufficient space for process information; use "-p MaxNumOfProcesses" option
  80.  
  81.  
  82. A: Proctool currently initializes with some fixed sized tables, including
  83. one to hold information for all active processes.  The defaults should be
  84. large enough for *most* users, however, if you are running a large server
  85. you can use the "-p" option to specify an upper bound on the number of
  86. processes that you expect.  For example:
  87.  
  88.  
  89.     proctool -p 1000
  90.  
  91.  
  92. Q:  How do I change the default background color in Proctool ?
  93.  
  94.  
  95. A:  Through your X defaults file.   The easiest way is to add an entry
  96. in your $HOME/.Xdefaults file which looks like this:
  97.  
  98.  
  99. proctool.*.background:   grey    # or some other color
  100.  
  101.  
  102. Q: How do I change the default colors used in the various graphs ?
  103.  
  104.  
  105. A: Currently ProCtool allocates only 8 colors for the graphs.  By
  106. default, it would look like this in a X resource file.  To change it,
  107. make the necessary modifications:
  108.  
  109.  
  110. proctool.graph_color_1: green
  111.  
  112. proctool.graph_color_2: blue
  113.  
  114. proctool.graph_color_3: yellow
  115.  
  116. proctool.graph_color_4: red
  117.  
  118. proctool.graph_color_5: purple
  119.  
  120. proctool.graph_color_6: orange
  121.  
  122. proctool.graph_color_7: aquamarine
  123.  
  124. proctool.graph_color_8: magenta
  125.  
  126.  
  127. Q: Do you support non-OpenWindow environments ?
  128.  
  129.  
  130. A: Proctool is written using Motif under OpenWindows.  It requires the
  131. Motif library libXm.so.3 under either /usr/dt/lib or /opt/SUNWmotif/lib.
  132. ICCCM compliant and is known to work under olwm, olvwm, mwm, and oswm.
  133. But the authors do have not the resources to test or support under other X 
  134. environments or window managers.
  135.  
  136.  
  137.  
  138. Q: How do I file a bug ?
  139.  
  140.  
  141. A: Send a bug report to the authors with as much detail as possible.  In all 
  142. cases, we would need to know at least the architecture (Sparc/Intel), the 
  143. Solaris version, any kernel patches that have been applied, the number of CPUs.
  144. When possible, please try to include a set of commands which reproduces
  145. the problem.  Even more helpful would be a core file or a traceback from
  146. dbx or adb.
  147.  
  148.  
  149. Q: Can I get sources to ProCtool ?
  150.  
  151.  
  152. A: We are not distributing sources to ProCtool.
  153.  
  154.  
  155.  
  156. *
  157. proctool_win
  158. ProCtool
  159.  
  160.  
  161. ProCtool is a tool for monitoring and controlling processes on a system.
  162. Most windows within Proctool has a help panel associated with it.  More
  163. detailed help can be found in the User's manual.
  164.  
  165.  
  166.  
  167. The main window is split into three main panes, the Control Area, the Process
  168. Area, and the System Area.  The Control area (on top) contains control and
  169. status information for proctool.  The Process Area is a list of processes
  170. similar to "ps(1)" output which are selectable with the mouse button.  (When
  171. a process is selected, a window of detailed, process-specific
  172. information is displayed.)  The System Area (on the bottom) contains system-wide
  173. information along with with a per-CPU information line.  This area is also
  174. mouse selectable to view in-depth system statistics.
  175.  
  176.  
  177. The buttons on top of the main window control ProCtool in the following manner:
  178.  
  179.  
  180. FILE       - Show the transcript file, turn on data logging, and save current
  181. ProCtool state into a startup file.
  182.  
  183.  
  184. VIEW       - Change the display characteristics of proctool.
  185.  
  186.  
  187. COMMANDS   - Manipulate the state of the current processes.
  188.  
  189.  
  190. GRAPH      - Graph system or process behavior.
  191.  
  192.  
  193. PROPERTIES - Set properties for the tool, or display process or system properties.
  194.  
  195.  
  196. *
  197. log_win
  198. Data Log Property Window
  199.  
  200.  
  201. The Data Log Property Window allows the user to log the state of the
  202. system and processes into a file for future analysis.  The file is
  203. in ASCII format and written in a way that allows for easy text manipulation
  204. via awk/sed/perl.
  205.  
  206.  
  207. You can log system characteristics, a set of selected variables for up 
  208. to 8 processes, or some very detailed characteristics of one process.
  209. Keep in mind, that certain operations such as Process Backtrace is very
  210. time consuming so that a very low sampling periods should be avoided.
  211. *
  212. monitor_win
  213. Monitor Window
  214.  
  215.  
  216. A monitor is a user definable 'event' that triggers the execution of user
  217. definable actions.
  218.  
  219.  
  220. A monitor consists of an logical expression and a set of actions.  When
  221. an active monitor is defined, it will apply the monitors expression
  222. against the data.   For every process expression which evaluates to true,
  223. the associated action is performed.  (Note that monitors are evaluated
  224. in the same order as they are in the Monitor window.  This means that
  225. the last active monitor will take precedence when conflicting visual
  226. actions are specified.)
  227.  
  228.  
  229. To create a monitor, enter an expression in the Expression input line
  230. and a select a set of actions in Action pane.   All monitors must be
  231. named and entered into the list of available monitors.  This is done
  232. by selecting the INSERT button near the center of the window.
  233.  
  234.  
  235. A monitor expression is a logical expression constructed from relational
  236. operators, constants, and predefined variables.  The predefined variables
  237. are the various fields from the process window along with some special
  238. system wide variables.   Values may be integer, hexadecimal, floating point,
  239. or string values.
  240.  
  241.  
  242. When a monitor is active, its expression is applied against each process.  The
  243. evaluation occurs when a new active monitor is defined  and every time
  244. a new sample is taken.  (Only those monitors which are active will be evaluated;
  245. active monitors are shown with a leading asterisk.)
  246.  
  247.  
  248. Monitors can generate a number of predefined or user defined actions.  Two
  249. of the simplest are the "Visual" and "Hide" actions which cause the entry
  250. for a process to change color or disappear, respectively.  The "Beep" action
  251. generates an audible bell when the monitor is triggered.  The "Popup"
  252. action will cause a popup window to appear which will show the process
  253. id's of the first ten processes that triggered the monitor.  (The remaining
  254. processes can be seen in the transcript.)
  255.  
  256.  
  257. A more complicated action is "Mail" which sends mail when the monitor
  258. expression evaluates true.  By default, the mail is sent to the person
  259. running proctool with a short message stating the command, process id
  260. and monitor expression which generated the action.  You also have the
  261. ability, via the "Edit Mail Template" button to customize the standard
  262. template.  See "Help" under the "Compose Mail" window for more information.
  263.  
  264.  
  265. The most general action is "Command" which invokes an arbitrary shell
  266. command, after expanding predefined variables like $USER, $CMD, and $PID
  267. to their actual values from the process which triggered the monitor.
  268.  
  269.  
  270. NOTE:  The current version of proctool will hang until the generated
  271. command is completed.
  272.  
  273.  
  274. Monitors by default trigger for an indefinite period of time once they
  275. are activated.   This "Monitor State" toggle allows the user to change
  276. that behavior.  Selecting ONCE implies that the monitor will trigger
  277. exactly once and then deactivate itself.
  278.  
  279.  
  280. *
  281. tool_prop_win
  282. Tool Properties
  283.  
  284.  
  285. This property window allows the user to set properties associated with
  286. ProCtool.
  287.  
  288.  
  289. Auto Update toggles whether the process window will automatically
  290. be updated after a Proctool-invoked command.  If this feature is turned
  291. on, the process window is updated after say a "Kill process" command.
  292. This has the affect of keeping the process window in sync with the state
  293. of the processes when issuing a lot of commands.
  294.  
  295.  
  296. You may also select whether the transcript file will be appended to 
  297. an existing transcript or will instead overwrite an existing file on 
  298. startup (via "Transcript Mode).
  299.  
  300.  
  301. The name of the transcript filename may be changed.  The change takes
  302. place immediately.  In order for this change to take affect on the
  303. next invocation of Proctool, you will need to save the current state.
  304. *
  305. sort_win
  306. Sort Window
  307.  
  308.  
  309. This window allows the user to specify what fields to use to sort the
  310. processes visible in the process window.   To specify a sort, select one
  311. or more variables (fields) to be used as sort keys.   Multiple key sorts
  312. are allowed with up to 20 keys.
  313.  
  314.  
  315. By default, ProCtool sorts in ascending order.  To sort in descending
  316. order, select "Sort Descending" before selecting the sort key.  Descending
  317. sort keys are denoted with a leading '~' character.
  318.  
  319.  
  320. *
  321. viewpoint_win
  322. Viewpoint Window
  323.  
  324.  
  325. This window allows the user to select which process fields are to be
  326. displayed in the process window.   To create a viewpoint, select
  327. a set of variables and "Apply" them.
  328.  
  329.  
  330. Viewpoints can be saved for later selection by assigning a name under
  331. "Viewpoint Name" and inserting it into the viewpoint database.  You
  332. may later re-select this viewpoint and "Apply" it.
  333.  
  334.  
  335. *
  336. mail_win
  337. Compose Mail
  338.  
  339.  
  340. This window allows you to customize a mail message to be sent by proctool
  341. when a monitor is triggered.  All predefined variables, like $USER,
  342. $CMD, $PID, $RSS, $CPU, etc will be expanded to the actual values from the
  343. process which triggered the monitor.
  344.  
  345.  
  346. To customize the mail message, just edit the "Compose Mail" popup window.  The
  347. edited template now becomes associated with the action for this
  348. particular monitor.  All other unedited monitor mail templates are not
  349. affected.
  350.  
  351.  
  352. *
  353. priocntl_win
  354. Process Control Window
  355.  
  356.  
  357. This window controls process binding and priority.
  358.  
  359.  
  360. The first menu, "Bind to Processor #" allows you to select a set of
  361. processes (via the selection mechanism in the main display) and
  362. bind them to a particular processor (or alternatively, to unbind them).  Note
  363. that this does not inhibit other processes from migrating to
  364. this processor, however, it does keep the selected processes from
  365. migrating away.
  366.  
  367.  
  368. The second menu, "Change Priority To" allows you to control the scheduling
  369. class (and parameters) of one or more processes.  Under the "Time-Share"
  370. selection, you can set the Time-Sharing Priority and Priority Limit.  Under
  371. "Real-Time", you can set the Real-Time Priority, Time Quanta, and
  372. Time Resolution.
  373.  
  374.  
  375. Users without root privileges may change the priority of only their processes.
  376.  
  377. *
  378. signal_win
  379. Signal Command Window
  380.  
  381.  
  382. This command window allows the user to send a selected signal to all
  383. processes selected in the main ProCtool process window.   The user must
  384. be running in privileged mode in order to send a signal to a process
  385. running under an effective user ID other than their own.
  386.  
  387.  
  388. *
  389. cpucntl_win
  390. Processor Command Window
  391.  
  392.  
  393. This window allows you to disable or enable particular processors.  Note that
  394. you are not allowed to disable ALL processors simultaneously, and you must
  395. have "root" privileges to successfully execute this operation.
  396. *
  397. process_win
  398. Process Detail Window
  399.  
  400. This window allows you to look a some very detailed information about a
  401. process.  The information provided here is not shown in the main process
  402. window since it is typically very expensive to do for all the processes.
  403. Unless you have "root" privileges, you cannot use this window
  404. on another user's process.
  405.  
  406.  
  407. Turning on the Auto-Update mode make this window refresh its data at
  408. the same sampling period as the main process window.   The Update Once
  409. button does this as a one-shot event.
  410.  
  411.  
  412. For multi-threaded programs, the LWP window lets you select which
  413. LWP you want look at.  The LWP selection is turned on only for
  414. the Traceback, Resources, and I/O selections.  The other selections
  415. apply to the process as a whole, and not to any individual LWP.
  416. *
  417. system_win
  418. System Detail Window
  419.  
  420.  
  421. This window gives some detailed information regarding the system as a whole.
  422.  
  423.  
  424. Turning on the Auto-Update mode make this window refresh its data at
  425. the same sampling period as the main process window.   The Update Once
  426. button does this as a one-shot event.
  427.  
  428.  
  429. The Hardware Configuration window is not very interesting right now
  430. but expect that to be enhanced in some future release.  Also, unfortunately
  431. the I/O statistics are not synchronized with the I/O graphs right now.
  432. That will be fixed in some future release as well.
  433. *
  434.